/*
 * Javlov - a Java toolkit for reinforcement learning with multi-agent support.
 * 
 * Copyright (c) 2009 Matthijs Snel
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package net.javlov;

/**
 * Represents any environment in which Agents can execute Actions. The Environment
 * returns the State an Agent currently finds itself in, based on the Agent's Action. It is
 * also responsible for providing reward based on a given State.
 * The Environment API is loosely based on the RL-Glue API introduced by the RLAI.
 *
 * @author Matthijs Snel
 * @version 0.2, 16/05/2009
 * @see Action
 * @see Agent
 * @see State
 */
public interface Environment<T> {
	
	/**
     * Executes the given action for the given agent.
     *
     * @param a The action to execute.
     * @param agent The agent that executes the action. 
     * @return the reward the agent receives for executing the action given the state it was in
     */
	public double executeAction( Action act, Agent a );
	
	/**
     * Returns the observation corresponding to the current state of a given agent.
     *
     * @param  agent Agent of which to return the state observation.
     * @return Observation of the state the agent is in.
     */
	public State<T> getObservation( Agent a );

	/**
	 * Returns the dimensionality of the observations the environment returns
	 */
	public int getObservationDim();
	
	/**
	 * Initializes the environment.
	 */
	public void init();
	
	/**
	 * Resets the environment to the, or a, starting state. Usually this corresponds to
	 * e.g. the beginning of a new episode in which the agent must be returned to a
	 * starting state.
	 */
	public void reset();
}
